Welcome to our API documentation. At MaritzCX, we know that it’s not enough for your users to be able to access CX data through our graphical user interface. Your systems need to speak directly to ours.

The MaritzCX ReST APIs let you do this by giving you programmatic access to key parts of the MaritzCX platform, including Survey Management, Case Management, and Data Import.

Notes: 1. To use the APIs, you must use the correct URL for your geographic location, detailed in the Getting Started sections of Survey Management, Case Management, and Data Import. Otherwise your calls will fail. 2. To use the MaritzCX API, you must have access to the MaritzCX platform. If you do not, contact your CX lead. You should also make sure to get an account for the MaritzCX Knowledge Center, which contains comprehensive detail on the tasks you will be performing within the MaritzCX platform. Again, contact your CX lead if you need to get an account.

Any registered user can call the APIs. However, in order to use most of the methods under the Survey Management API, you will need login credentials that have one of the following permissions:

• Survey Owner – This is simply the user account either that created or currently owns the survey itself.
• Survey System Administrator – This permission is set for the user in the admin area of the MaritzCX platform.
• System Administrator – This permission is set for the user in the admin area of the MaritzCX platform.

Note: To make sure your API user has either Survey System Administrator or System Administrator privilege, see the Survey Ownership instructions under Retrieving Data.

To use the Case Management API, you just need to make sure the following is true:

• Case Management is enabled for the company.
• The logged-in user has access to some cases – the case worker view is all that is exposed (i.e. Case Admin functions are not exposed by the API).

To use the Data Import API, you must be one of the following:

• Survey Owner – This is simply the user account either that created or currently owns the survey itself.
• Survey Analyst
• Survey Manager

The MaritzCX Survey Management API allows you to programmatically perform various aspects of survey administration, from creating email lists to sending invitations and reminders, prepopulating survey questions, inserting respondent data, managing opt-outs, and many other important tasks.

The response data-oriented methods within the Survey Management API return response list data in a JSON payload, allowing you to then consume that data in a variety of ways – such as pushing it into a database that is linked to your CRM or other third party application.

The following entity relationship diagram shows how the various objects within the API are related:

For first steps in using the API, see the topics Retrieving Data and Sending Batch Email Invitations.

In order to use most of the methods under the Survey Management API, you will need login credentials that have one of the following permissions:

• Survey Owner – This is simply the user account either that created or currently owns the survey itself.
• Survey System Administrator – This permission is set for the user in the admin area of the MaritzCX platform.
• System Administrator – This permission is set for the user in the admin area of the MaritzCX platform.

Note: To make sure your API user has either Survey System Administrator or System Administrator privilege, see the Survey Ownership instructions under Retrieving Data.

To connect to the Survey Management API, use the following as your base URL:

North America – https://sampleapi.allegiancetech.com

Europe, the Middle-East, and Africa – https://sampleapi.mcxplatform.de

Australia – https://sampleapi.mcxplatform.com.au

To keep the API performant for all consumers, the MaritzCX platform implements rate limiting. That means that in a given time period you will only be allowed to send a certain number of requests/pull a certain amount of data. We’ve kept these limits high enough to allow standard usage of the API while still low enough to prevent abuse of the service.

The following limits apply to endpoints within the Survey Management API:

• The endpoint getEmailListImportStatus enforces the following rate limit: you can call the endpoint up to once per minute.
• The endpoint getEmailListRecipientStatusListV2 enforces the following rate limit: you can call the endpoint up to once per minute.
• The endpoint getOptOuts implements an export limitation. The default limit is defined as 50,000 opt-outs per hour.
• The endpoint getResponsesBySurveyId implements an export limitation. The default limit is defined as 50,000 responses per hour, where one response means the set of answers a respondent has given to complete a survey (i.e. all the answers contained in one survey response).
• The endpoint getRespondentsBySurveyId also implements an export limitation. The default limit is defined as 50,000 respondents per hour.
• The endpoint getTextAnalyticsResponsesBySurveyId shares an export limitation with endpoint getResponsesBySurveyId. The default limit is defined as 50,000 responses per hour (regardless which of these methods is used), where one response means the set of answers a respondent has given to complete a survey (i.e. all the answers contained in one survey response).
• The endpoint newEmailListV2 enforces the following rate limit: you can call the endpoint up to once per minute.
• The endpoint sendInvitationForNewRecipients enforces the following rate limits: you can call the endpoint up to once per minute, and you can export up to 500 records per minute.

The following limits apply to endpoints within the Data Import API:

• 1 request per second
• 10,000 requests per day

If the rate limit is exceeded then you will receive an HTTP 429 response with following message in the body:

“Rate limit exceeded. Please try again later.”

MaritzCX customers can use the Survey Management API to pull data from the MaritzCX platform. This document describes sample API calls for common scenarios.

Assumptions

• The customer pulls the MaritzCX data into their data warehouse.
• The customer would like to future-proof the integration with MaritzCX. Data from new or changed surveys and questions should flow into the data warehouse without the need to make any changes to the integration itself.
• Data is loaded daily.

(for the example below)

• Current time is 29 July 2017, 02:00 AEST.
• Data is loaded between 02:00 and 03:00 AEST.
• Previous day: 28 July 2017 00:00 – 29 July 2017 00:00 AEST.
• Previous day in UTC time: 27 July 2017 14:00 – 28 July 2017 14:00.

Survey Ownership

Note: If you do not have access to the MaritzCX platform, contact your CX lead. You should also make sure to get an account for the MaritzCX Knowledge Center, which contains comprehensive detail on the tasks you will be performing within the MaritzCX platform. Again, contact your CX lead if you need to get an account.

1. Create a role for the API user. Log into the MaritzCX platform and select the gear icon to go to Platform Administration. From there, go to User Management | Application Access Roles. On this page, select Add New, then check the boxes Survey System Administrator and System Administrator:

In the field marked Role Name, enter “API User”, then scroll to the bottom of the screen and select Save Role.

2. Next, go to User Management | User Profiles and create a platform user (“apiuser@customer.com”) who will own all surveys which should be pushed into your data warehouse. Assign it the role “API User” that you just created.

The API will use this user to log into the platform API.

Data Model

API Request Overview

With the exception of GET ping, requests should be sent as an HTTP POST. Set the Accept header to “Accept: application/json”, and set the Content-type header to “Content-type: application/json”. The request parameters should be placed in the body of the HTTP request.

Here is a Curl example of a valid request:

curl -H "Accept: application/json" -H "Content-type: application/json" -X POST -d '{"userName" : "apiuser@customer.com", "password" : "secret", "companyName" : "demo.aus.allegiancetech.com"}' https://sampleapi.aus.allegiancetech.com/EmailImport.HttpService.svc/web/authenticate

Retrieve Response Data

1. Call authenticate – Provide a valid username, password, and the company name for the user with the role “API User”.

[your region’s base URL here]/HttpService.svc/web/authenticate

{"userName": "apiuser@customer.com",
"password": "secret",
"companyName": "demo.aus.allegiancetech.com"
}

[your region’s base URL here]/HttpService.svc/web/getSurveyList

{"token": "8544621e-ba51-4db8-bff4-2d5a1e2d9ea3"}

3. Retrieve all questions from the surveys returned in step 2, then loop through the list of surveys returned by getSurveyList and call for each survey (using surveyId):

[your region’s base URL here]/HttpService.svc/web/getQuestionsBySurveyId

{"token": "496d9aea-2436-4a15-8e46-09156851cf06",
"surveyId" : 6
}

4. Retrieve all answers from the surveys returned in step 2, then loop through the list of surveys returned by getSurveyList and call for each survey (using surveyId):

[your region’s base URL here]/HttpService.svc/web/getAnswersBySurveyId

{"token": "496d9aea-2436-4a15-8e46-09156851cf06",
"surveyId" : 6
}

5. Retrieve all respondents from the previous day to the surveys returned in step 2, then loop through the list of surveys returned by getSurveyList and call for each survey (using surveyId and a filter on CompletedDate):

[your region’s base URL here]/HttpService.svc/web/getRespondentsBySurveyId

{"token": "d0ad4fef-2285-429c-813f-64336fd3ca86",
"surveyId" : 6,
"filterXml" : “

CompletedDate
Between
2017-07-27T14:00:00
2017-07-28T14:00:00

"
}

www.timeanddate.com is a useful tool to manage this. On it, select Time Zones | Time Zone Converter, input your local time zone, and select “Include UTC Time in Results”. You can then see the UTC time that will be needed.

You must also use the ISO 8601 date/time format for all filterXML date/time parameters.

Store the result in a table called “mcx_respondents”.

6. Retrieve all responses from the previous day to the surveys returned in step 2, then loop through the list of surveys returned by getSurveyList and call for each survey. To do so, use surveyId and a filter on ModifiedDate (ModifiedDate ensures that the request picks up any responses manually updated after the response was submitted):

[your region’s base URL here]/HttpService.svc/web/getResponsesBySurveyId

{"token": "d0ad4fef-2285-429c-813f-64336fd3ca86",
"surveyId" : 6,
"filterXml" : “

ModifiedDate
Between
2017-07-27T14:00:00
2017-07-28T14:00:00

"
}

Store the result in a table called “mcx_responses”. Also note that the number of rows in this table can be significant.

Retrieve Email Invitation Data

7. Retrieve all email lists uploaded during the previous 7 days for the surveys returned in step 2, then loop through the list of surveys returned by getSurveyList and call for each survey (using surveyId and a filter on UploadedOn for the past 7 days). Specifying the last 7 days ensures that the request will return any asynchronous bounces which we delivered well after sending the emails.

[your region’s base URL here]/HttpService.svc/web/getEmailListsBySurveyId

{"token": "d0ad4fef-2285-429c-813f-64336fd3ca86",
"surveyId" : 6,
"filterXml" : “

UploadedOn
Between
2017-07-27T14:00:00
2017-07-28T14:00:00

"
}

8. Retrieve the recipient status of the email lists returned in step 7, then loop through the list of email lists returned by getEmailListsBySurveyId and call for each email list (using emailListId).

[your region’s base URL here]/HttpService.svc/web/getEmailListRecipientStatusListV2

{"token": "8544621e-ba51-4db8-bff4-2d5a1e2d9ea3",
"emailListId" : 6152
}

9. Retrieve the survey opt-outs from the previous day to the surveys returned in step 2, then loop through the list of surveys returned by getSurveyList and call for each survey (using surveyId and a filter on RequestedDate):

[your region’s base URL here]/HttpService.svc/web/getOptOuts

{"token": "d0ad4fef-2285-429c-813f-64336fd3ca86",
"surveyId" : 6,
"filterXml" : “

RequestedDate
Between
2017-07-27T14:00:00
2017-07-28T14:00:00

"
}

Optional – Limit Which Questions Should be Returned

You may wish to limit the questions being returned by getResponsesBySurveyId. You may for example not wish to retrieve all feedfile data. To achieve this, follow these steps:

Create a standard question tag for all of the questions you would like to store in your data warehouse. For example, the question tag of any question that should get loaded into the data warehouse can start with “DW_”.

[your region’s base URL here]/HttpService.svc/web/getQuestionsBySurveyId; with a filter defined as “QuestionShortCode Contains DWH_”

{"token": "8238a7f7-8423-41e4-937c-8c667ddb4ff9",
"surveyId" : 6,
"filterXml":"QuestionShortCodeContainsDWH"
}

{"token": "ea2327cf-74c1-44cd-b308-0955e4adebd9",
"surveyId" : 6,
"filterXml" : "

CompletedDate
Between
2017-07-27T14:00:00
2017-07-28T14:00:00

QuestionIds
Equals
143,144

"
}

MaritzCX has a number of ways to collect survey responses. One way is to invite people to take a survey via email. In order to send the emails, the MaritzCX platform requires a .CSV file to be supplied to the platform. This file is loaded into an email list, and then email invitations are sent to the email addresses in the email list.

When a .CSV file is loaded into an email list, its columns are “mapped” to questions in the survey, as described in this Knowledge Center article. These questions are referred to as “pre-pop” or pre-populated questions. These pre-pop questions can be used in the survey to either display information about the recipient in the survey, e.g. show their account type, or used in conditional logic to display a question relevant to the recipient, or used to hold operational data, e.g. agent name or agent team for filtering/grouping when reporting.

You can load the .CSV files and send invitations through the MaritzCX platform GUI either manually (as in the Knowledge Center article above), or using an automated upload (loading files from the MaritzCX SFTP), or using the MaritzCX API. Note that if the MaritzCX API is used to load an email list, invitations can only be scheduled and sent either manually through the MaritzCX platform GUI or via the MaritzCX API. The MaritzCX platform does not support using the GUI to configure automated scheduling of invitations sent to email list created via the API.

This document describes how to use the MaritzCX API to load an email list and send email invitations.

Survey Ownership

Note: If you do not have access to the MaritzCX platform, contact your CX lead. You should also make sure to get an account for the MaritzCX Knowledge Center, which contains comprehensive detail on the tasks you will be performing within the MaritzCX platform. Again, contact your CX lead if you need to get an account.

1. Create a role for the API user. Log into the MaritzCX platform and select the gear icon to go to Platform Administration. From there, go to User Management | Application Access Roles.

2. Next, go to User Management | User Profiles and create a platform user (“apiuser@customer.com”) who will own all surveys which should be pushed into your data warehouse. Assign it the role “API user”.

You should then always use this user to log into the API.

Prepare Email List File

When sending email lists via the MaritzCX GUI or loading an email list via SFTP, the user is required to supply a .CSV file containing the list of recipients with their email addresses, as well as other data that will be pre-populated into the survey questions, for example operational data such as account number, etc.

The minimum required is a column containing an email address. The MaritzCX API sends this same .CSV content via the API. You will need to prepare the content in a similar way.

Refer to the Sample Email List File for more details. For the purposes of this document, all sample requests will be made with the following email list:

Email,Question1,Question2
user@domain.com,A,B

Prepare Mapping File

Create a mapping file. This file will contain mapping information that tells the API how the columns in your email list file are related to system fields and pre-populated survey questions. The mapping file is also used to map each recipient to a Survey Language using the SystemFieldName=”Language”.

To produce the mapping file you will need:

• The survey code of your survey;
• The column names of the feed file;
• The corresponding question tags of your prep-pop questions;
• A de-duplicated email list file.

Refer to the Sample Mapping File for more details.

Note: To ignore duplicate invitees (dedupe) when importing the email list file, set the attribute DuplicateRule of element EmailListMappingDefinition to “0”.

For the purposes of this document all example requests will be made with the following mapping file:

<!--?xml version="1.0" encoding="utf-8" ?-->

user@notifcationdomain.com

API Request Overview

With the exception of GET ping, requests should be sent as an HTTP POST. Set the Accept header to “Accept: application/json”, and set the Content-type header to “Content-type: application/json”. The request parameters should be placed in the body of the HTTP request.

Here is a Curl example of a valid request:

curl -H "Accept: application/json" -H "Content-type: application/json" -X POST -d '{"userName" : "apiuser@customer.com", "password" : "secret", "companyName" : "demo.aus.allegiancetech.com"}' https://sampleapi.aus.allegiancetech.com/EmailImport.HttpService.svc/web/authenticate

Sequence Diagram

Authenticate

Provide a valid username, password, and the company name for the user with the role “API user”. Store the token returned in the response for future API requests.

curl -s --request POST --url https://sampleapi.mcxplatform.com.au/EmailImport.HttpService.svc/web/authenticate \
--header 'content-type: application/json' \
--data '{
"userName": "apiuser@customer.com",
"password": "yourAPIUser",
"companyName": "yourCompanyName"
}'

Sample Response

{
"AuthenticateResult":"8544621e-ba51-4db8-bff4-2d5a1e2d9ea3"
}

Retrieve Survey Code and Survey Id

Call getSurveyList to retrieve all surveys owned by apiuser@customer.com. Note that this user will only see surveys owned by apiuser@customer.com.

curl -s --request POST --url https://sampleapi.mcxplatform.com.au/EmailImport.HttpService.svc/web/getSurveyList \
--header 'content-type: application/json' \
--data '{
"token": "8544621e-ba51-4db8-bff4-2d5a1e2d9ea3"}
}'

Sample Response

{
"GetSurveyListResult":[
{
"Active":true,
"CutOffDate":null,
"Description":"First Survey",
"InactiveDate":null,
"Source":1,
"SurveyCode":"4JANRX",
"SurveyId":1
}
]
}

SurveyCode is required in the Mapping File. SurveyId is required when scheduling invitations and reminders.

Refer to getSurveyList for more information.

Retrieve Invitation Template Ids

Call getSurveyInvitationTemplates to retrieve invitation template ids for the survey.

curl -s --request POST --url https://sampleapi.mcxplatform.com.au/EmailImport.HttpService.svc/web/getSurveyInvitationTemplates \
--header 'content-type: application/json' \
--data '{
"token": "8544621e-ba51-4db8-bff4-2d5a1e2d9ea3",
"surveyId": 1
}'

Sample Response

{
"GetSurveyInvitationTemplatesResult": {
"InvitationTemplatesEmailList": [
{
"InvitationtemplateId": 8101,
"LanguageId": 446334,
"LanguageName": "English",
"MessageBody": "...",
"Subject": "Your feedback is vital to serving you better"
},
{
"InvitationtemplateId": 8120,
"LanguageId": 446334,
"LanguageName": "English",
"MessageBody": "...",
"Subject": "Template for doc"
}
],
"Surveyid": 1,
"TemplateType": 0
}
}

InvitationtemplateId is required when scheduling invitations.

Retrieve Reminder Template Ids

Call getSurveyReminderTemplates to retrieve reminder template ids for the survey.

curl -s --request POST --url https://sampleapi.mcxplatform.com.au/EmailImport.HttpService.svc/web/getSurveyReminderTemplates \
--header 'content-type: application/json' \
--data '{
"token": "8544621e-ba51-4db8-bff4-2d5a1e2d9ea3",
"surveyId": 1
}'

Sample Response

{
"GetSurveyReminderTemplatesResult": {
"InvitationTemplatesEmailList": [
{
"InvitationtemplateId": 8121,
"LanguageId": 446334,
"LanguageName": "English",
"MessageBody": "...",
"Subject": "Test Reminder for Doc"
}
],
"Surveyid": 1,
"TemplateType": 1
}
}

InvitationtemplateId is required when scheduling reminders.

Note: Each template has 1 language. If you are using multiple languages, refer to getSurveyReminderTemplates.

Create Email List

You create an email list by calling the endpoint newEmailListV2.

The request body contains:

• The token
• The name of the email list to be created
• Email list file as an unsigned byte array
• Mapping File as an unsigned byte array

Note: Both Email List File and Mapping File must be converted to byte array. Each byte must be represented as an unsigned integer. The resulting array is added to the JSON request.

See the Sample Request under newEmailListV2 for an example request body that contains an encoded email list file and mapping file.

See Encoding Implementation Examples for sample encoding algorithms.

Call newEmailListV2.

curl -s --request POST --url https://sampleapi.mcxplatform.com.au/EmailImport.HttpService.svc/web/newEmailListV2 \
--header 'content-type: application/json' \
--data '{
"token":"8544621e-ba51-4db8-bff4-2d5a1e2d9ea3",
"emailListFile":[239, 187, 191, ],
"mappingFile":[],
"emailListName":"My First Email List"
}'

Sample Response

{
"NewEmailListV2Result":{
"DataImportId":1206,
"ErrorMessage":""
}
}

Schedule Email Invitations

Call insertInvitationSchedule
curl -s --request POST --url https://sampleapi.mcxplatform.com.au/EmailImport.HttpService.svc/web/insertInvitationSchedule \
--header 'content-type: application/json' \
--data '{
"token":"8544621e-ba51-4db8-bff4-2d5a1e2d9ea3",
"surveyId":"1",
"sampleIds":"1190",
"templateIds":"8101",
"startTime":"1/12/2019 8:55AM",
"startTimeCulture":"en-GB",
"startTimeZoneId":"AUS Eastern Standard Time"
}'

Notes:

• sampleIds use the EmailListId returned by getEmailListImportStatus.
• templateIds can be found by calling endpoint getSurveyInvitationTemplates. You can also find it in the platform URL when editing a template:

• startTime is in the format D/M/YYYY h:ma if you are using startTimeCulture:”en-GB”
• Ensure startTime is in the future. For example, assume your process runs at 9AM each day and schedules invites for 10AM the same day. If your processing is delayed until after 10AM, you may wish to either set startTime to “now” to send immediately or 10AM the next day.
• startTimeZoneId is a .Net timezone reference. For the list of Microsoft Time Zone Index Values, see this page.

If you are using multiple languages, specify a comma-separated list of template IDs, e.g. “templateIds”:”8101,8102,8103″.

The API will automatically map the value in the language field (specified in SystemFieldName=”Language”) to the language name of the email template (“LanguageName”).

Sample Response

{
"InsertInvitationScheduleResult":"OK"
}

Refer to insertInvitationSchedule for more information on the endpoint.

Schedule Reminder Emails (Optional)

If reminders are required call insertReminderSchedule.

curl -s --request POST --url https://sampleapi.mcxplatform.com.au/EmailImport.HttpService.svc/web/insertReminderSchedule \
--header 'content-type: application/json' \
--data '{
"token":"8544621e-ba51-4db8-bff4-2d5a1e2d9ea3",
"surveyId":"1",
"sampleIds":"1190",
"templateIds":"8121",
"startTime":"1/12/2019 8:55AM",
"startTimeCulture":"en-GB",
"startTimeZoneId":"AUS Eastern Standard Time"
}'

• sampleIds use the EmailListId returned by getEmailListImportStatus.
• templateIds can be found by calling the endpoint getSurveyInvitationTemplates. You can also find it in the platform URL when editing a template:

• startTime is in the format D/M/YYYY h:ma, which is an absolute time for the reminders to be sent. Typically in production reminders will be sent 5-7 days after the initial invitation is sent. To assist end-to-end testing of your survey program, it is recommended that you ensure it is easy to adjust when the when the reminders are sent, e.g. for UAT, schedule reminders 1 hour after invitations.
• startTimeZoneId is a .Net timezone reference. For the list of Microsoft Time Zone Index Values, see this page.

If you are using multiple languages, specify a comma-separated list of template IDs, e.g.
“templateIds”:”8121,8122,8123″,

The API will automatically map the value in the language field (specified in SystemFieldName=”Language”) to the language name of email template (“LanguageName”).

Sample Response

{
"InsertReminderScheduleResult":"OK"
}

The answer depends on how quickly the customer would like to download the responses from our platform. The process outlined below assumes a daily download that occurs around 2AM (though a similar concept will work for hourly downloads):

1. Call authenticate.

2. Call getSurveyList. This returns a list of all surveys the authenticated user (used in authenticate) has access to.

3. Loop through the list returned by getSurveyList:

a. Get the latest questions – call getQuestionsBySurveyId (e.g. What is your gender?) –> the result is a reference table with questions.

b. Get the latest answers – call getAnswersBySurveyId (e.g. the set of answers to the question “What is your gender?”: male, female –> the result is a reference table with possible answers.

4. Call getResponsesBySurveyId with a filter on Completed date (retrieve yesterday’s responses).

• The unique key for the result is on ResponseId
• To avoid duplication, do an “upsert” in the target database using ResponseId as the unique key.

5. End loop.

This concludes the process of retrieving all responses for an ongoing open survey, without any duplication.

See above. getSurveyList will return all surveys from all users (depending on the access level of the user logged in using authenticate).

See above. Set a filter using the “Completed date”. To prevent any duplicates (a survey result could be manually updated), you “upsert” using the unique key set to ResponseId.

Authenticates a client. authenticate must be called to retrieve a token, which is required by subsequent requests.

URL

Parameters

userName=[string]      Required
Username of the user that will be authenticated.

password=[string]      Required
Password of the user that will be authenticated.

companyName=[string]      Required
A specific value within the MaritzCX platform that identifies the customer. To get this value, see this Knowledge Center article. The MaritzCX Knowledge Center contains comprehensive detail on the tasks you will be performing within the MaritzCX platform. Contact your CX lead if you do not have an account.

Sample Request

{  
   "userName":"johnque@email.com",
   "password":"password",
   "companyName":"generalindustries.allegiancetech.com"
}

Response Values

AuthenticateResult=[Guid]

A Guid authentication token required by subsequent service calls.

Sample Response

{  
   "AuthenticateResult":"c3f90919-5b36-4711-b796-782dbd75fe43"
}

Error Response

See the Error Responses section for the various error responses possible.

Sample Call

curl -X POST --header 'Content-Type: application/json' --header 'Accept: application/xml' -d '{ \ 
   "userName": "randy.matlock%40example.com", \ 
   "password": "Blabbus_99", \ 
   "companyName": "generalindustries.allegiancetech.com" \ 
 }' 'https://sampleapi.allegiancetech.com/HttpService.svc/web/authenticate'

Notes

Templates are used to give a standard form to email invitations and reminders. createInvitationTemplateBySurveyId allows you to create your own invitation templates for a given survey ID.

URL

Parameters

token=[Guid]      Required
Authentication token, which is retrieved by calling authenticate.

surveyId=[int]      Required
The ID of the survey that the invitation belongs to. To find the survey Id, see this Knowledge Center article. For a readout of all surveys the authenticated user has access to, issue the call getSurveyList.

languageId=[int]      Required
The languageId for the invitation. To get the language IDs available for the survey, first issue getLanguagesBySurveyId.

invitationTemplateName=[string]      Required
The name or description of the template. Required if the source is “Bonfire”.

isDefault=[bool]      Optional
Flag set if the template is the default template for the given survey. Valid only for surveys whose source is “Bonfire”. Will default to “false” if omitted.

invitationSubject=[string]      Required
Subject for the invitation email.

fromName=[string]      Required
Sender’s name for the invitation email.

fromEmail=[string]      Required
Sender’s email for the invitation email.

invitationText=[string]      Required
Content for the invitation email.

source=[string]      Optional
Source of the reminder. Currently “Bonfire” and “Desktop” are accepted. Will default to “Bonfire” if the value passed in is anything other than “Desktop”.

Sample Request

{
  "token": "691038b0-e2fe-456e-a849-1d3f92d9436d", 
  "surveyId":20, 
  "languageId":31, 
  "invitationTemplateName":"Test Template for doc.", 
  "isDefault":"true", 
  "invitationSubject":"Template for doc", 
  "fromName":"Test name", 
  "fromEmail":"test@maritzcx.com", 
  "invitationText":"
    <!DOCTYPE html>
      <html>
        <body>
          <h1>My First Template</h1>
          <p>My first template.</p>
        </body>
      </html>",
  "source":"Bonfire"
}

Response Values

CreateInvitationTemplateBySurveyIdResult=[string]

A string representation of the inserted object with the new templateId. Contains the following elements:

• TemplateId – The identifier of the template.
• SurveyId – The identifier of the survey.
• LanguageId – The identifier of the template language. For a readout of the survey’s languages, issue the call getLanguagesBySurveyId.
• Subject – The subject of the email template.
• FromName – The “From” name of the email template.
• FromEmail – The “From” email of the email template.
• ReplyEmail – The “Reply” email of the email template.
• Message – HTML body of the email message.
• Description – The description of the email template.
• IsDefault – A boolean value which indicates whether or not the template is the default one. Possible values are “True” and “False”.
• TemplateType – Indicates whether the template is for an Invitation or Reminder.
• Source – Source of the invitation. Possible values are “Bonfire” and “Desktop”.

Sample Response

{  
   TemplateId:72,
   SurveyId:85,
   LanguageId:19,
   Subject:Test Invitation for Doc,
   FromName:Test Name,
   FromEmail:test@maritzcx.com,
   ReplyEmail:test@maritzcx.com,
   Message:
    <!DOCTYPE html>
      <html>
        <body>
          <h1>My First Invitation</h1>
          <p>This is an invitation.</p>
        </body>
      </html>,
   Description:Test Invitation for Doc,
   IsDefault:False,
   TemplateType:Invitation,
   Source:Bonfire
}

Error Response

Error responses are detailed here.

Sample Call

curl -X POST --header 'Content-Type: application/json' --header 'Accept: application/xml' -d '{ \ 
   "token": "c3f90919-5b36-4711-b796-782dbd75fe43", \ 
   "surveyId":20, \ 
   "languageId":31, \ 
   "invitationTemplateName": "Test Template for doc.", \ 
   "isDefault": "true", \ 
   "invitationSubject": "Template for doc", \ 
   "fromName": "Test name", \ 
   "fromEmail": "test@maritzcx.com", \ 
   "invitationText": "<!DOCTYPE html>
      <html>
        <body>
          <h1>My First Template</h1>
          <p>My first template.</p>
        </body>
      </html>", \ 
   "source": "Bonfire" \ 
 }' 'https://sampleapi.allegiancetech.com/HttpService.svc/web/createInvitationTemplateBySurveyId'

Notes

Templates are used to give a standard form to email invitations and reminders. createReminderTemplateBySurveyId allows you to create your own reminder templates for a given survey ID.

URL

Parameters

token=[Guid]      Required
Authentication token, which is retrieved by calling authenticate.

surveyId=[int]      Required
The ID of the survey that the reminder belongs to. To find the survey Id, see this Knowledge Center article. For a readout of all surveys the authenticated user has access to, issue the call getSurveyList.

languageId=[int]      Required
The languageId for the reminder. To get the language IDs available for the survey, first issue getLanguagesBySurveyId.

reminderTemplateName=[string]      Required
The name or description of the template. Required if the source is “Bonfire”.

isDefault=[bool]      Optional
Flag set if the template is the default template for the given survey. Valid only for surveys whose source is “Bonfire”. Will default to “false” if omitted.

reminderSubject=[string]      Required
Subject for the reminder email.

fromName=[string]      Required
Sender’s name for the reminder email.

fromEmail=[string]      Required
Sender’s email for the reminder email.

reminderText=[string]      Required
Content for the reminder email.

source=[string]      Optional
Source of the reminder. Currently “Bonfire” and “Desktop” are accepted. Will default to “Bonfire” if the value passed in is anything other than “Desktop”.

Sample Request

{
   "token":"6591ba61-0386-4997-b2b8-ede834e4bc2b",
   "surveyId":20,
   "languageId":31,
   "reminderTemplateName":"Test Reminder for Doc",
   "isDefault":"true",
   "reminderSubject":"Test Reminder for Doc",
   "fromName":"Test Name",
   "fromEmail":"test@maritzcx.com",
   "reminderText":"
    <!DOCTYPE html>
      <html>
        <body>
          <h1>My First Reminder</h1>
          <p>This is a reminder.</p>
        </body>
      </html>",
   "source":"Bonfire"
}

Response Values

CreateReminderTemplateBySurveyIdResult=[string]

A string representation of the inserted object with the new templateId. Contains the following elements:

• TemplateId – The identifier of the template.
• SurveyId – The identifier of the survey.
• LanguageId – The identifier of the template language. For a readout of the survey’s languages, issue the call getLanguagesBySurveyId.
• Subject – The subject of the email template.
• FromName – The “From” name of the email template.
• FromEmail – The “From” email of the email template.
• ReplyEmail – The “Reply” email of the email template.
• Message – HTML body of the email message.
• Description – The description of the email template.
• IsDefault – A boolean value which indicates whether or not the template is the default one. Possible values are “True” and “False”.
• TemplateType – Indicates whether the template is for an Invitation or Reminder.
• Source – Source of the invitation. Possible values are “Bonfire” and “Desktop”.

Sample Response

{  
   TemplateId:86,
   SurveyId:20,
   LanguageId:31,
   Subject:Test Reminder for Doc,
   FromName:Test Name,
   FromEmail:test@maritzcx.com,
   ReplyEmail:test@maritzcx.com,
   Message:
    <!DOCTYPE html>
      <html>
        <body>
          <h1>My First Reminder</h1>
          <p>This is a reminder.</p>
        </body>
      </html>,
   Description:Test Reminder for Doc,
   IsDefault:False,
   TemplateType:Reminder,
   Source:Bonfire
}

Error Response

Error responses are detailed here.

Sample Call

curl -X POST --header 'Content-Type: application/json' --header 'Accept: application/xml' -d '{ \ 
   "token": "6591ba61-0386-4997-b2b8-ede834e4bc2b", \ 
   "surveyId":20, \ 
   "languageId":31, \ 
   "reminderTemplateName": "Test Reminder for Doc", \ 
   "isDefault": "true", \ 
   "reminderSubject": "Test Reminder for Doc", \ 
   "fromName": "Test Name", \ 
   "fromEmail": "test@maritzcx.com", \ 
   "reminderText": "<!DOCTYPE html>
      <html>
        <body>
          <h1>My First Reminder</h1>
          <p>This is a reminder.</p>
        </body>
      </html>", \ 
   "source": "Bonfire" \ 
 }' 'https://sampleapi.allegiancetech.com/HttpService.svc/web/createReminderTemplateBySurveyId'

Notes

Gets a filtered list of answers that are defined for a given survey ID.

Note: It’s important to emphasize that “answers” do not refer a survey taker’s responses to questions, but rather to pre-defined answer choices for questions that have those.

URL

Parameters

token=[Guid]      Required
Authentication token, which is retrieved by calling authenticate.

surveyId=[int]      Required
Specifies the survey for which survey answers will be returned. To find the survey Id, see this Knowledge Center article. For a readout of all surveys the authenticated user has access to, issue the call getSurveyList.

filterXml=[string]      Optional
A parameter in XML format to filter the result records. The filter must have the following XML format:

<FilterDefinition>
  <FilterGroup GroupOperator='...'>
    <FilterCriteria>
      <FilterColumn></FilterColumn>
      <FilterOperator></FilterOperator>
      <FilterValue></FilterValue>
      <FilterValue></FilterValue>
    </FilterCriteria>
    <FilterCriteria>
      ...
    </FilterCriteria>
      ...
  </FilterGroup>
</FilterDefinition>

The FilterGroup GroupOperator can be defined with the operators AND and OR. Here are the columns available for filters, their possible values if applicable, and the operators that can be used on them:

• QuestionId; identifier of the question; (Equals, NotEquals); for a readout of the survey’s questions, issue the call getQuestionsBySurveyId.
• LanguageId; identifier of the language; (Equals, NotEquals); for a readout of the survey’s languages, issue the call getLanguagesBySurveyId; if no LanguageId is defined in the filter you will receive answers in the default survey language.
• ScaleId; identifier of the scale; (Equals, NotEquals); for a readout of the survey’s scales, issue the call getScalesBySurveyId.
• AnswerShortCode; answer’s tag that is used to identify an answer by a different name; (Equals, NotEquals, Contains, NotContains)
• AnswerDataType; these are the possible values for AnswerDataType: ordinal (single and multi-type questions); rank-other; ordinal-other; text (short text questions); number; memo (long text questions); datetime; (Equals, NotEquals, Contains, NotContains)
• AnswerId; identifier of the answer; (Equals, NotEquals)

Notes: 1. Only a single FilterGroup per FilterDefinition is supported. 2. To find values for AnswerId and AnswerDataType, first issue getAnswersBySurveyId with no filters.

xmlIndent=[bool]      Optional
Specifies whether or not the resulting XML structure is formatted with newlines and indentation. Allowed parameters are true and false.

Sample Request

{
   "token":"f152254f-eee1-4b37-b18d-07d8ed8dbeb9",
   "surveyId":123,
   "filterXml":"
   <FilterDefinition>
     <FilterGroup GroupOperator='AND'>
       <FilterCriteria>
         <FilterColumn>QuestionId</FilterColumn>
         <FilterOperator>Equals</FilterOperator>
         <FilterValue>1</FilterValue>
       </FilterCriteria>
     </FilterGroup>
   </FilterDefinition>",
   "xmlIndent":"true"
}

Response Values

GetAnswersBySurveyIdResult=[string]

A collection of answers in XML representation. GetAnswersBySurveyIdResult has the following XML structure:

{
    "GetAnswersBySurveyIdResult": "<Answers>
      <Answer>
        <AnswerId>1</AnswerId>
        <QuestionId>1</QuestionId>
        <ScaleId>1</ScaleId>
        <AnswerDataType>ordinal</AnswerDataType>
        <AnswerText>Option 1</AnswerText>
        <AnswerWeight>0</AnswerWeight>
        <AnswerShortCode>OPTION_1</AnswerShortCode>
        <ModifiedDate />
      </Answer>
      <Answer>
        <AnswerId>2</AnswerId>
        <QuestionId>1</QuestionId>
        <ScaleId>1</ScaleId>
        <AnswerDataType>ordinal</AnswerDataType>
        <AnswerText>Option 2</AnswerText>
        <AnswerWeight>0</AnswerWeight>
        <AnswerShortCode>OPTION_2</AnswerShortCode>
        <ModifiedDate />
      </Answer>
      <Answer>
        <AnswerId>3</AnswerId>
        <QuestionId>1</QuestionId>
        <ScaleId>1</ScaleId>
        <AnswerDataType>ordinal</AnswerDataType>
        <AnswerText>Option 3</AnswerText>
        <AnswerWeight>0</AnswerWeight>
        <AnswerShortCode>OPTION_3</AnswerShortCode>
        <ModifiedDate />
      </Answer>
  </Answers>"
}

Here are definitions for the XML fields:

• AnswerId – Identifier of the answer. For a readout of the survey’s answers, issue the call getAnswersBySurveyId.
• QuestionId – Identifier of the question. For a readout of the survey’s questions, issue the call getQuestionsBySurveyId.
• ScaleId – Scales identify various answer groups for a given question. A question can have multiple answer groups if they are in a table. ScaleId is the identifier for these answer groups. For a readout of the survey’s scales, issue the call getScalesBySurveyId.
• AnswerDataType – Indicates the type of answer. These go hand-in-hand with question types. These are the possible values for AnswerDataType: ordinal (single and multi-type questions); rank-other; ordinal-other; text (short text questions); number; memo (long text questions); datetime.
• AnswerText – The text of an answer, as entered when the survey is created in Survey Builder. Empty for textbox-type questions where the ‘Store text responses as categorical’ option is not selected.
• AnswerWeight – Survey builders can place weights on the answers. This reflects the weight value on the answer.
• AnswerShortCode – Answer’s tag that is used to identify an answer by a different name.
• ModifiedDate – Date when the answer was saved; this value is only set by the data import process. Returned in ISO8601 format and the UTC time zone.

Note: The GetAnswersBySurveyId response contains an XML formatted string. When this response is serialized to JSON for transmission, some XML characters may be escaped using backslash characters. In order to retrieve valid XML from the response, the raw JSON response will need to be first converted to a JSON object. When that happens then the XML string property can be retrieved from the JSON object.

Here is sample C# code that does this:

// Using the Newtonsoft.Json Library
JObject jsonObject = JObject.Parse(rawResponse);
var validXmlString = jsonObject["GetAnswersBySurveyIdResult"].ToString();

Sample Response

{
    "GetAnswersBySurveyIdResult": "<Answers>
      <Answer>
        <AnswerId>1</AnswerId>
        <QuestionId>1</QuestionId>
        <ScaleId>1</ScaleId>
        <AnswerDataType>ordinal</AnswerDataType>
        <AnswerText>Option 1</AnswerText>
        <AnswerWeight>0</AnswerWeight>
        <AnswerShortCode>OPTION_1</AnswerShortCode>
        <ModifiedDate />
      </Answer>
      <Answer>
        <AnswerId>2</AnswerId>
        <QuestionId>1</QuestionId>
        <ScaleId>1</ScaleId>
        <AnswerDataType>ordinal</AnswerDataType>
        <AnswerText>Option 2</AnswerText>
        <AnswerWeight>0</AnswerWeight>
        <AnswerShortCode>OPTION_2</AnswerShortCode>
        <ModifiedDate />
      </Answer>
      <Answer>
        <AnswerId>3</AnswerId>
        <QuestionId>1</QuestionId>
        <ScaleId>1</ScaleId>
        <AnswerDataType>ordinal</AnswerDataType>
        <AnswerText>Option 3</AnswerText>
        <AnswerWeight>0</AnswerWeight>
        <AnswerShortCode>OPTION_3</AnswerShortCode>
        <ModifiedDate />
      </Answer>
  </Answers>"
}

Error Response

Error responses are detailed here.

Sample Call

curl -X POST --header 'Content-Type: application/json' --header 'Accept: application/xml' -d '{ \ 
   "token": "f152254f-eee1-4b37-b18d-07d8ed8dbeb9", \ 
   "surveyId": 123, \ 
   "filterXml": "<FilterDefinition>
     <FilterGroup GroupOperator='AND'>
       <FilterCriteria>
         <FilterColumn>QuestionId</FilterColumn>
         <FilterOperator>Equals</FilterOperator>
         <FilterValue>1</FilterValue>
       </FilterCriteria>
     </FilterGroup>
   </FilterDefinition>", \ 
   "xmlIndent": "true" \ 
 }' 'https://sampleapi.allegiancetech.com/HttpService.svc/web/getAnswersBySurveyId'

Notes

// Using the Newtonsoft.Json Library
JObject jsonObject = JObject.Parse(rawResponse);
var validXmlString = jsonObject["GetAnswersBySurveyIdResult"].ToString();

Gets a list of errors that occurred during the import of a given email list.

URL

Parameters

token=[Guid]      Required
Authentication token, which is retrieved by calling authenticate.

dataImportId=[integer]      Required
The ID of the email list whose errors will be retrieved.

Sample Request

{
   "token":"f152254f-eee1-4b37-b18d-07d8ed8dbeb9",
   "dataImportId":1206
}

Response Values

GetEmailListImportErrorsV2Result=[List]

A list of EmailImportErrorItemV2 objects. Contains the following elements:

• ColumnName – Name of the column in the import file where the error occurred.
• ColumnNumber – Number of the column in the import file where the error occurrred.
• ErrorDescription – Description of the error.
• ErrorDetails – Details of the error.
• RowNumber – Row number in the import file where the error occurred.
• RowValues – Values in the row of the import file where the error occurred.
• ColumnValue – Value in the column of the import file where the error occurred.

Sample Response

{  
   "GetEmailListImportErrorsV2Result":[  
      {  
         "ColumnName":"Q2 Email",
         "ColumnNumber":2,
         "ErrorDescription":"Duplicate email address",
         "ErrorDetails":"graypye@gmail.com",
         "RowNumber":6,
         "RowValues":[  
            {  
               "ColumnName":"Q1 AuthKey",
               "ColumnValue":"ak5"
            },
            {  
               "ColumnName":"Q2 Email",
               "ColumnValue":"graypye@gmail.com"
            },
            {  
               "ColumnName":"Q3 Language",
               "ColumnValue":"English"
            },
            {  
               "ColumnName":"Q4 First Name",
               "ColumnValue":"Gray"
            },
            {  
               "ColumnName":"Q5 Last Name",
               "ColumnValue":"Pye"
            },
            {  
               "ColumnName":"Q6 Salutation",
               "ColumnValue":"Sir"
            },
            {  
               "ColumnName":"Q7 Other1",
               "ColumnValue":"a"
            },
            {  
               "ColumnName":"Q8 Other2",
               "ColumnValue":"c"
            },
            {  
               "ColumnName":"Q9 Other3",
               "ColumnValue":"e"
            },
            {  
               "ColumnName>":"Q10 Other4",
               "ColumnValue":"g"
            },
            {  
               "ColumnName":"Q11 Other5",
               "ColumnValue":"i"
            },
            {  
               "ColumnName":"Q12 Other6",
               "ColumnValue":"k"
            },
            {  
               "ColumnName":"Q13 Other7",
               "ColumnValue":"m"
            },
            {  
               "ColumnName":"Q14 Other8",
               "ColumnValue":"x"
            },
            {  
               "ColumnName":"Q15 Other9",
               "ColumnValue":"x"
            },
            {  
               "ColumnName":"Q16 Other10",
               "ColumnValue":"x"
            }
         ]
      }
   ]
}

Error Response

Error responses are detailed here.

Sample Call

curl -X POST --header 'Content-Type: application/json' --header 'Accept: application/xml' -d '{ \ 
   "token": "f152254f-eee1-4b37-b18d-07d8ed8dbeb9", \ 
   "dataImportId": 1206 \ 
 }' 'https://sampleapi.allegiancetech.com/HttpService.svc/web/getEmailListImportErrorsV2'

Notes

Gets the status of an email list import.

URL

Parameters

token=[Guid]      Required
Authentication token, which is retrieved by calling authenticate.

dataImportId=[integer]      Required
The ID of the data import, which is retrieved by calling newEmailListV2.

Sample Request

{  
   "token":"f152254f-eee1-4b37-b18d-07d8ed8dbeb9",
   "dataImportId":1206
}

Response Values

GetEmailListImportStatusResult=(JSON object)

Response object for getEmailListImportStatus, which contains the following elements:

• ChooseManyAsSingleColumn – Unused by the API and therefore always returns as False.
• ColNumber – Column number that contained an error.
• CsvError – Unused.
• CurrentItemNum – Unused.
• DataImportName – Name of the data import, as specified in the MaritzCX platform.
• DataImportType – Integer type of the data import; typically will be a 13, which represents an API sample import.
• DelimiterCharacter – Character used to separate data values in the import file. Possible values are “,” and “;”.
• DeliverableId – Internal, not to be used by customer.
• EmailListId – Identifier of the email list.
• ErrorMessage – Message describing the error that was generated.
• ExceptionMessage – TBD
• FileName – Name of the email list data file.
• HasError – Boolean that indicates whether or not the email list import has an error.
• ImportStatus – Status of the import; possible values are: 1 = File uploaded – Data from the import file has been inserted into a staging table; 10 = Import complete – The import has successfully completed (END state); 12 = Mapping required – The import file has been uploaded to our system and the import process has started; 14 = Importing/Validating – The data from the staging table is being processed; 15 = Import error – There has been an error somewhere in the import process (END state); 16 = No invitees to import – After validation, there were not invitees left to import (END state); 20 = Creating TAC answers – Text as categorical answer creation has started.
• ItemCount – Unused.
• NotificationEmails – Email addresses of all notification recipients.
• OriginalFileName – Original filename of the imported file.
• RowNumber – Row number that contained an error.
• ScheduledImportDefinitionId – For an automated import, identifies the import definition.
• SurveyId – Identifier of the MaritzCX survey associated with the email list.
• SurveyName – Name of the MaritzCX survey associated with the email list.

Sample Response

{
  "GetEmailListImportStatusResult": {
    "ImportStatus": 10,
    "CurrentItemNum": 0,
    "ItemCount": 0,
    "NotificationEmails": "foo.smith@allegiance.com,foosmith@gmail.com",
    "SurveyId": 68,
    "DataImportName": "myListName",
    "FileName": "352bfd00-0afe-4cd7-9bcf-e7ddd5d9e375.csv",
    "OriginalFileName": "",
    "DelimiterCharacter": ",",
    "ScheduledImportDefinitionId": "",
    "SurveyName": "My Survey",
    "DeliverableId": 0,
    "EmailListId": 1190,
    "CsvError": {
      "HasError": true,
      "ErrorMessage": "string",
      "RowNumber": 1,
      "ColNumber": 1,
      "ExceptionMessage": "string"
    },
    "DataImportType": "ResponseImport",
    "ChooseManyAsSingleColumn": true
  }
}

Error Response

Error responses are detailed here.

Note: If you are using newEmailListV2 to import the file you can specify a notification email address, and that email address should receive a detailed import email, including the appropriate error code if applicable. If importing through the platform the notification email can be set during the import setup process.

Sample Call

curl -X POST --header 'Content-Type: application/json' --header 'Accept: application/xml' -d '{ \ 
   "token": "f152254f-eee1-4b37-b18d-07d8ed8dbeb9", \ 
   "dataImportId": 1206 \ 
 }' 'https://sampleapi.allegiancetech.com/HttpService.svc/web/getEmailListImportStatus'

Notes

Gets the status of all recipients in a given email list.

URL

Parameters

token=[Guid]      Required
Authentication token, which is retrieved by calling authenticate.

emailListId=[int]      Required
ID of the email list whose recipient status will be retrieved.

Sample Request

{  
   "token":"f152254f-eee1-4b37-b18d-07d8ed8dbeb9",
   "emailListId":1190
}

Response Values

GetEmailListRecipientStatusListV2Result=[list]

Contains the following elements:

• AuthenticationKey – Authentication key for the associated survey.
• EmailAddress – Email address of the recipient.
• InvitationStatusCode – Status of the invitation. Can be any of the following values: 6 = Uploaded; 7 = Invited; 15, 17, 18 = Hard Bounce; 16 = Soft Bounce; 21 = Fatigued; 22 = Sampled Out (Opt Out)
• InvitedDate – Date and time when the invitation was sent, in the date format yyyy-MM-ddTHH:mm:ssZ. Returned in ISO8601 format and the UTC time zone.
• IsOptedOut – Boolean that indicates whether or not the recipient has opted out of survey invitations; possible values are “true” and “false”.
• ReminderDate – Date and time when the reminder was sent, in the date format yyyy-MM-ddTHH:mm:ssZ. Returned in ISO8601 format and the UTC time zone.
• ResponseStatusCode – Status of the response. Can be any of the following values: 0 = Completed; 2 = In Progress; 3 = Abandoned; 12 = No Response

Sample Response

{  
   "GetEmailListRecipientStatusListV2Result":[  
      {  
         "AuthenticationKey":"BZRSQ9",
         "EmailAddress":"email1@gmail.com",
         "InvitationStatusCode":6,
	 "InvitedDate": "2018-06-18T08:57:08Z",
         "IsOptedOut":false,
	 "ReminderDate": "",
         "ResponseStatusCode":12
      },
      {  
         "AuthenticationKey":"D4FE2E",
         "EmailAddress":"email2@allegiance.com",
         "InvitationStatusCode":6,
	 "InvitedDate": "2018-06-18T08:57:08Z",
         "IsOptedOut":false,
	 "ReminderDate": "",
         "ResponseStatusCode":12
      },
      {  
         "AuthenticationKey":"H599B4",
         "EmailAddress":"email3@gmail.com",
         "InvitationStatusCode":6,
	 "InvitedDate": "2018-06-18T08:57:08Z",
         "IsOptedOut":false,
	 "ReminderDate": "",
         "ResponseStatusCode":12
      },
      {  
         "AuthenticationKey":"UWDU5J",
         "EmailAddress":"email4@gmail.com",
         "InvitationStatusCode":6,
	 "InvitedDate": "2018-06-18T08:57:08Z",
         "IsOptedOut":false,
	 "ReminderDate": "",
         "ResponseStatusCode":12
      },
      {  
         "AuthenticationKey":"ZWWVCT",
         "EmailAddress":"email5@gmail.com",
         "InvitationStatusCode":6,
	 "InvitedDate": "2018-06-18T08:57:07Z",
         "IsOptedOut":false,
	 "ReminderDate": "2018-06-25T12:40:37Z",
         "ResponseStatusCode":12
      }
   ]
}

Error Response

Error responses are detailed here.

Sample Call

curl -X POST --header 'Content-Type: application/json' --header 'Accept: application/xml' -d '{ \ 
   "token": "f152254f-eee1-4b37-b18d-07d8ed8dbeb9", \ 
   "emailListId": 1190 \ 
 }' 'https://sampleapi.allegiancetech.com/HttpService.svc/web/getEmailListRecipientStatusListV2'

Notes

Returns a response list matching the given parameters.

URL

Parameters

token=[Guid]      Required
Authentication token, which is retrieved by calling authenticate.

surveyId=[int]      Required
Id of the survey the email lists should be provided for. To find the survey Id, see this Knowledge Center article. For a readout of all surveys the authenticated user has access to, issue the call getSurveyList.

xmlIndent=[bool]      Optional
Specifies whether the resulting XML structure is formatted with newlines and indentation. Allowed parameters are true and false.

filterXml=[string]      Optional
A parameter in XML format to filter the result records. The filter must have the following XML format:

<FilterDefinition MaxNumberResultRecords='...'>
  <FilterGroup GroupOperator='...'>

    <FilterCriteria>
      <FilterColumn></FilterColumn>
      <FilterOperator></FilterOperator>
      <FilterValue></FilterValue>
      <FilterValue></FilterValue>
    </FilterCriteria>
    <FilterCriteria>
      ...
    </FilterCriteria>
    ...
  </FilterGroup>
</FilterDefinition>

FilterGroup GroupOperator can be defined with the operators AND and OR. Regarding FilterColumn, the following list gives the columns available for filters, their possible values if applicable, and the operators that can be used on them:

• EmailListId – ID of the email list (Equals, NotEquals)
• Description – Filter on the description of the email list (Equals, NotEquals, Contains, NotContains)
• InvitedOn – Date when the email list was sent out (GreaterThan, LessThan, Between)
• UploadedOn – Date when the email list was requested (GreaterThan, LessThan, Between)

Notes: 1. Only a single FilterGroup per FilterDefinition is supported. 2. The “Between” FilterOperator requires 2 FilterValues. The order is not relevant. 3. The FilterValue for date fields must use ISO 8601 date format: yyyy-MM-ddTHH:mm:ssZ. 4. The FilterValue for date fields must use the UTC time zone.

Sample Request

{
  "token": "f152254f-eee1-4b37-b18d-07d8ed8dbeb9",
  "surveyId": 123,
  "filterXml": "<FilterDefinition> <FilterGroup GroupOperator="AND"> <FilterCriteria> <FilterColumn>UploadedOn</FilterColumn> <FilterOperator>Between</FilterOperator> <FilterValue>2015-11-29T09:03:22Z</FilterValue> <FilterValue>2015-11-30T22:03:22Z</FilterValue> </FilterCriteria> </FilterGroup> </FilterDefinition>",
  "xmlIndent": "true"
}

Response Values

GetEmailListsBySurveyIdResult=[string]

An XML representation of the email lists matching the given parameters. Contains the following elements:

• EmailLists – Array of email lists returned by the query.
• EmailList – One email list returned by the query, composed of the elements below.
• EmailListId – ID of the email list being retrieved.
• Description – Text description of the email list being retrieved.
• SurveyId – ID of the survey the email list is attached to.
• UploadedOn – Date when the email list was requested. Returned in ISO8601 format and the UTC time zone.
• InvitedOn – Date when the email list was sent out. Returned in ISO8601 format and the UTC time zone.
• IsRolling – Whether or not it is a daily rolling, automatically generated email list.

Note: The getEmailListsBySurveyId response contains an XML-formatted string. When this response is serialized to JSON for transmission, some XML characters may be escaped using backslash characters. In order to retrieve valid XML from the response, the raw JSON response will need to be first converted to a JSON object. When that happens then the XML string property can be retrieved from the JSON object.

Here is sample C# code that does this:

// Using the Newtonsoft.Json Library
JObject jsonObject = JObject.Parse(rawResponse);
var validXmlString = jsonObject["getEmailListsBySurveyIdResult"].ToString();

Sample Response

HTTP Status Code: 200

{
"GetEmailListsBySurveyIdResult":"<EmailLists>
<EmailLists>
  <EmailList>
    <EmailListId>272</EmailListId>
    <Description>Test1</Description>
    <SurveyId>305</SurveyId>
    <UploadedOn>2017-03-10T10:30:12Z</UploadedOn>
    <InvitedOn />
    <IsRolling>false</IsRolling>
  </EmailList>
  <EmailList>
    <EmailListId>270</EmailListId>
    <Description>Test2</Description>
    <SurveyId>305</SurveyId>
    <UploadedOn>2017-03-09T13:42:55Z</UploadedOn>
    <InvitedOn />
    <IsRolling>false</IsRolling>
  </EmailList>
  <EmailList>
    <EmailListId>267</EmailListId>
    <Description>Test3</Description>
    <SurveyId>305</SurveyId>
    <UploadedOn>2017-03-08T13:55:19Z</UploadedOn>
    <InvitedOn />
    <IsRolling>false</IsRolling>
  </EmailList>
</EmailLists>"
}

Error Response

Error responses are detailed here.

Sample Call

curl -X POST --header 'Content-Type: application/json' --header 'Accept: application/xml' -d '{ \ 
   "token": "f152254f-eee1-4b37-b18d-07d8ed8dbeb9", \ 
   "surveyId": 123, \ 
   "filterXml": "<FilterDefinition> <FilterGroup GroupOperator="AND"> <FilterCriteria> <FilterColumn>UploadedOn</FilterColumn> <FilterOperator>Between</FilterOperator> <FilterValue>2015-11-29T09:03:22Z</FilterValue> <FilterValue>2015-11-30T22:03:22Z</FilterValue> </FilterCriteria> </FilterGroup> </FilterDefinition>",
  "xmlIndent": "true", \ 
 }' 'https://sampleapi.allegiancetech.com/HttpService.svc/web/getEmailListsBySurveyId'

Notes

Gets a list of invitation schedules for a given survey ID.

URL

Parameters

token=[Guid]      Required
Authentication token, which is retrieved by calling authenticate.

surveyId=[int]      Optional
Specifies the survey for which invitation schedules will be returned. To find the survey Id, see this Knowledge Center article. For a readout of all surveys the authenticated user has access to, issue the call getSurveyList.

filterXml=[string]      Optional
A parameter in XML format to filter the result records. The filter must have the following XML format:

<FilterDefinition>
<FilterGroup GroupOperator='...'>
<FilterCriteria>
<FilterColumn></FilterColumn>
<FilterOperator></FilterOperator>
<FilterValue></FilterValue>
<FilterValue></FilterValue>
</FilterCriteria>
<FilterCriteria>
...
</FilterCriteria>
...
</FilterGroup>
</FilterDefinition>

FilterColumn can be defined for the columns UTCStartTime (date) and SampleId (int). For SampleId (int), only the operator “Equals” is allowed.

FilterOperator can be defined with the operators Equals, NotEquals, GreaterThan, LessThan, and Between.

Notes: 1. Only a single FilterGroup per FilterDefinition is supported. 2. The “Between” FilterOperator requires 2 FilterValues. The order is not relevant. 3. The FilterValue for date fields must use ISO 8601 date format: yyyy-MM-ddTHH:mm:ssZ. 4. The FilterValue for date fields must use the UTC time zone.

xmlIndent=[bool]      Optional
Specifies whether the resulting XML is formatted with newlines and indentation. The allowed parameters are true and false.

Sample Request

{
"token":"f152254f-eee1-4b37-b18d-07d8ed8dbeb9",
"surveyId":123,
"filterXml":"
<FilterDefinition>
<FilterGroup GroupOperator=’AND’>
<FilterCriteria>
<FilterColumn>CompletedDate</FilterColumn>
<FilterOperator>Equals</FilterOperator>
<FilterValue>2015-12-04T03:26:00Z</FilterValue>
</FilterCriteria>
</FilterGroup>
</FilterDefinition>",
"xmlIndent":"true"
}

Response Values

GetInvitationSchedulesBySurveyIdResult=[string]

List of scheduled invitations in XML representation. Contains the following elements:

• InvitationScheduleID – Unique integer identifier of the invitation schedule.
• SurveyID – The integer identifier of the survey for which invitations will be sent.
• StartTime – Definition of the start date and time when invitations will be sent (in local server time). Returned in ISO8601 format and the UTC time zone.
• Stagger – Maximum number of emails that will be sent out per hour per campaign.
• SendOpen – Start time when invitations will be sent. The time is 24 hour-based, where 0 = 12:00 AM and 2300 = 11:00 PM.
• SendClose – End time when sending out invitations will be stopped. The time is 24 hour-based, where 0 = 12:00 AM and 2300 = 11:00 PM.
• SendDays – Days when an invitation will be sent out. The integer represents a bit field with each bit set to indicate that the day is used to send out invitations: 1 = Sunday; 2 = Monday; 4 = Tuesday; 8 = Wednesday; 16 = Thursday; 32 = Friday; 64 = Saturday; 127 = all days.
• SampleIDs – Internal integer identifiers (comma-separated) of email lists for which the invitations will be sent.
• UTCStartTime – Definition of the start date and time when invitations will be sent (in UTC time), e.g. 2015-12-04T03:22:34.
• UTCOffset – UTC time offset in hours when invitations will be sent, e.g. +5.
• UTCOffsetInMinutes – UTC time offset in minutes when invitations will be sent, e.g. 300.

Note: The getInvitationSchedulesBySurveyId response contains an XML formatted string. When this response is serialized to JSON for transmission, some XML characters may be escaped using backslash characters. In order to retrieve valid XML from the response, the raw JSON response will need to be first converted to a JSON object. When that happens then the XML string property can be retrieved from the JSON object.

Here is sample C# code that does this:

// Using the Newtonsoft.Json Library
JObject jsonObject = JObject.Parse(rawResponse);
var validXmlString = jsonObject["getInvitationSchedulesBySurveyIdResult"].ToString();

Sample Response

{
"GetInvitationSchedulesBySurveyIdResult":"<InvitationSchedules>
<InvitationSchedule>
<InvitationScheduleID>123</InvitationScheduleID>
<SurveyID>38</SurveyID>
<StartTime>2015-12-04T03:22:34</StartTime>
<Stagger>1</Stagger>
<SendOpen>2</SendOpen>
<SendClose>3</SendClose>
<SendDays>4</SendDays>
<SampleIDs>123</SampleIDs>
<UTCStartTime>2015-12-04T03:22:34</UTCStartTime>
<UTCOffset>+2</UTCOffset>
<UTCOffsetInMinutes>0</UTCOffsetInMinutes>
</InvitationSchedule>
<InvitationSchedule>
<InvitationScheduleID>124</InvitationScheduleID>
<SurveyID>38</SurveyID>
<StartTime>2015-12-04T04:22:34</StartTime>
<Stagger>1</Stagger>
<SendOpen>2</SendOpen>
<SendClose>3</SendClose>
<SendDays>4</SendDays>
<SampleIDs>123,124</SampleIDs>
<UTCStartTime>2015-12-04T03:22:34</UTCStartTime>
<UTCOffset>+3</UTCOffset>
<UTCOffsetInMinutes>0</UTCOffsetInMinutes>
</InvitationSchedule>
</InvitationSchedules>"
}

Error Response

Error responses are detailed here.

Sample Call

curl -X POST --header 'Content-Type: application/json' --header 'Accept: application/xml' -d '{ \ 
   "token": "f152254f-eee1-4b37-b18d-07d8ed8dbeb9", \ 
   "surveyId": 123, \ 
   "filterXml": "<FilterDefinition>
<FilterGroup GroupOperator=’AND’>
<FilterCriteria>
<FilterColumn>CompletedDate</FilterColumn>
<FilterOperator>Equals</FilterOperator>
<FilterValue>2015-12-04T03:26:00Z</FilterValue>
</FilterCriteria>
</FilterGroup>
</FilterDefinition>", \ 
   "xmlIndent": "true" \ 
 }' 'https://sampleapi.allegiancetech.com/HttpService.svc/web/getInvitationSchedulesBySurveyId'

Notes

Here is sample C# code that does this:

// Using the Newtonsoft.Json Library
JObject jsonObject = JObject.Parse(rawResponse);
var validXmlString = jsonObject["getInvitationSchedulesBySurveyIdResult"].ToString();

Gets a list of languages for a given survey ID.

URL

Parameters

token=[Guid]      Required
Authentication token, which is retrieved by calling authenticate.

surveyId=[int]      Required
Specifies the survey for which languages will be returned. To find the survey Id, see this Knowledge Center article. For a readout of all surveys the authenticated user has access to, issue the call getSurveyList.

filterXml=[string]      Optional
A parameter in XML format to filter the result records. The filter must have the following XML format:

<FilterDefinition>
  <FilterGroup GroupOperator='...'>
    <FilterCriteria>
      <FilterColumn></FilterColumn>
      <FilterOperator></FilterOperator>
      <FilterValue></FilterValue>
      <FilterValue></FilterValue>
    </FilterCriteria>
    <FilterCriteria>
      ...
    </FilterCriteria>
      ...
  </FilterGroup>
</FilterDefinition>

The FilterGroup GroupOperator can be defined with the operators AND and OR. The FilterColumn can be defined for the columns LanguageName or LanguageDescription. The FilterOperator can be defined with the operators Equals, NotEquals, GreaterThan, LessThan, and Between.

xmlIndent=[bool]      Optional
Specifies whether or not the resulting XML structure is formatted with newlines and indentation. Allowed parameters are true and false.

Sample Request

{
   "token":"f152254f-eee1-4b37-b18d-07d8ed8dbeb9",
   "surveyId":123,
   "filterXml":"",
   "xmlIndent":"true"
}

Response Values

GetLanguagesBySurveyIdResult=[string]

A collection of languages in XML representation. GetLanguagesBySurveyIdResult has the following XML structure:

<Languages>
  <SurveyLanguage>
    <LanguageId></LanguageId>
    <LanguageName></LanguageName>
    <LanguageDescription></LanguageDescription>
    <Default></Default>
  </SurveyLanguage>
  <SurveyLanguage>
    …
  </SurveyLanguage>
    …
</Languages>

Here are definitions for the XML fields:

• LanguageId – Identifier of the survey language.
• LanguageName – Name of the language.
• LanguageDescripton – A language description (e.g. native language name).
• Default – True if the language is the survey’s default language, otherwise False.

Note: The getLanguagesBySurveyId response contains an XML formatted string. When this response is serialized to JSON for transmission, some XML characters may be escaped using backslash characters. In order to retrieve valid XML from the response, the raw JSON response will need to be first converted to a JSON object. When that happens then the XML string property can be retrieved from the JSON object.

Here is sample C# code that does this:

// Using the Newtonsoft.Json Library
JObject jsonObject = JObject.Parse(rawResponse);
var validXmlString = jsonObject["getLanguagesBySurveyIdResult"].ToString();

Sample Response

{
   "GetLanguagesBySurveyIdResult":"
     <Languages>
       <SurveyLanguage>
         <LanguageId>11</LanguageId>
         <LanguageName>English</LanguageName>
         <LanguageDescription>English</LanguageDescription>
         <Default>true</Default>
       </SurveyLanguage>
       <SurveyLanguage>
         <LanguageId>12</LanguageId>
         <LanguageName>French</LanguageName>
         <LanguageDescription>Français</LanguageDescription>
         <Default>false</Default>
       </SurveyLanguage>
       <SurveyLanguage>
         <LanguageId>13</LanguageId>
         <LanguageName>German</LanguageName>
         <LanguageDescription>Deutsch</LanguageDescription>
         <Default>false</Default>
      </SurveyLanguage>
    </Languages>"
}

Error Response

Error responses are detailed here.

Sample Call

curl -X POST --header 'Content-Type: application/json' --header 'Accept: application/xml' -d '{ \ 
   "token": "f152254f-eee1-4b37-b18d-07d8ed8dbeb9", \ 
   "surveyId": 123, \ 
   "filterXml": "", \ 
   "xmlIndent": "true" \ 
 }' 'https://sampleapi.allegiancetech.com/HttpService.svc/web/getLanguagesBySurveyId'

Notes

// Using the Newtonsoft.Json Library
JObject jsonObject = JObject.Parse(rawResponse);
var validXmlString = jsonObject["getLanguagesBySurveyIdResult"].ToString();

Returns an opt-out list matching the given parameters.

URL

Parameters

token=[Guid]      Required
Authentication token, which is retrieved by calling authenticate.

sOptOutType=[string]      Optional
Type of email opt-out; one of the following: Survey (the email address is opted out of only the particular survey specified by the surveyId), Site (the email address is opted out of all surveys from your site), Domain (all email addresses from the email domain are opted out of the survey). Note: “Site” in the API is equivalent to “Company” in the GUI.

surveyId=[string] Optional
If sOptOutType = “Survey”, the ID of the survey to be opted out. To find the survey Id, see this Knowledge Center article. For a readout of all surveys the authenticated user has access to, issue the call getSurveyList.

filterDefinitionXml=[string]      Optional
A parameter in XML format to filter the result records. The filter must have the following XML format:

<FilterDefinition MaxNumberResultRecords="…">
<FilterGroup GroupOperator='…'>
<FilterCriteria>
<FilterColumn></FilterColumn>
<FilterOperator></FilterOperator>
<FilterValue></FilterValue>
<FilterValue></FilterValue>
</FilterCriteria>
<FilterCriteria>
…
</FilterCriteria>
…
</FilterGroup>
</FilterDefinition>

FilterGroup GroupOperator can be defined with the operators AND and OR. The following list gives the columns available for filters, their possible values if applicable, and the operators that can be used on them:

• OptOutEmail – Specified email addresses for the opt-opt (Equals, NotEquals, Contains, NotContains).
• OptOutType – Type of email opt-out; one of the following: Survey (the email address is opted out of only the particular survey specified by the surveyId), Site (the email address is opted out of all surveys from your site), Domain (all email addresses from the email domain are opted out of the survey).
• RequestedDate – Date when the opt-out was requested (GreaterThan, LessThan, Between).
• EmailListId – ID of the email list where the opt-out is used (Equals, NotEquals).
• Description – Filter on the description of the email list (Equals, NotEquals, Contains, NotContains).

Notes: 1. Only a single FilterGroup per FilterDefinition is supported. 2. The “Between” FilterOperator requires 2 FilterValues. The order is not relevant. 3. The FilterValue for date fields must use ISO 8601 date format: yyyy-MM-ddTHH:mm:ssZ. 4. The FilterValue for date fields must use the UTC time zone.

surveyId=[int]      Optional
A nullable survey id for the opt outs to be returned. If the surveyId is either null or zero then the sOptOutType should be ‘Site’ or ‘Domain’, if not then the sOptOutType should be ‘Survey’.

Sample Request

{
"token": "ef458ea7-5e44-4857-8e6b-d33d8691e0df",
"sOptOutType":"Site",
"surveyId":0,
"filterDefinitionXml":"<FilterDefinition><FilterGroup GroupOperator=\"OR\"><FilterCriteria><FilterColumn>RequestedDate</FilterColumn><FilterOperator>Between</FilterOperator><FilterValue Type=\"Date\">2009-07-16T08:28:01Z</FilterValue><FilterValue Type=\"Date\">2019-07-17T08:28:01Z</FilterValue></FilterCriteria> </FilterGroup></FilterDefinition>"
}

Response Values

GetOptOutsResult=[string]

An XML representation of the opt outs matching the given parameters. GetOptOutsResult has the following XML structure:

<OptOuts>
<OptOutRecipient>
<OptOutEmail></OptOutEmail>
<OptOutType></OptOutType>
<SurveyId></SurveyId>
<RequestedDate></RequestedDate>;
</OptOutRecipient>
<OptOutRecipient>
...
</OptOutRecipient>
...
</OptOuts>

Here are definitions for the XML fields:

• OptOutEmail – The email address that has been opted out.
• OptOutType – Type of email opt-out; one of the following: Survey (the email address is opted out of only the particular survey specified by the surveyId), Site (the email address is opted out of all surveys from your site), Domain (all email addresses from the email domain are opted out of the survey). If OptOutType = “Site” then SurveyId = 0.
• SurveyId – ID of the survey that has been opted out of. Same as the identifier discussed in this Knowledge Center article.
• RequestedDate – Date and time when the opt-out request was made. Comes in ISO 8601 format; comes in the time zone of your local MaritzCX server: North America – Central Time Zone, EMEA – Central European, APAC – Australian Eastern.

Note: The getOptOuts response contains an XML formatted string. When this response is serialized to JSON for transmission, some XML characters may be escaped using backslash characters. In order to retrieve valid XML from the response, the raw JSON response will need to be first converted to a JSON object. When that happens then the XML string property can be retrieved from the JSON object.

Here is sample C# code that does this:

// Using the Newtonsoft.Json Library
JObject jsonObject = JObject.Parse(rawResponse);
var validXmlString = jsonObject["getOptOutsResult"].ToString();

Sample Response

{
"GetOptOutsResult":"<OptOuts>
<OptOutRecipient>
<OptOutEmail>123@test.com</OptOutEmail>
<OptOutType>Survey</OptOutType>
<SurveyId>12</SurveyId>
<RequestedDate>2019-12-01T06:39:49</RequestedDate>
</OptOutRecipient>
<OptOutRecipient>
<OptOutEmail>kg@test.com</OptOutEmail>
<OptOutType>Survey</OptOutType>
<SurveyId>12</SurveyId>
<RequestedDate>2019-07-01T10:50:59</RequestedDate>
</OptOutRecipient>
<OptOutRecipient>
<OptOutEmail>randall.matlock@jetski.com</OptOutEmail>
<OptOutType>Site</OptOutType>
<SurveyId>0</SurveyId>
<RequestedDate>2019-02-15T16:23:06</RequestedDate>
</OptOutRecipient>
</OptOuts>"
}

Error Response

Error responses are detailed here.

Sample Call C#

curl -X POST --header 'Content-Type: application/json' --header 'Accept: application/xml' -d '{ \
"token": "ef458ea7-5e44-4857-8e6b-d33d8691e0df", \
"sOptOutType": "Site", \
"surveyId": 123, \
"filterDefinitionXml": "<FilterDefinition><FilterGroup GroupOperator=\"OR\"><FilterCriteria><FilterColumn>RequestedDate</FilterColumn><FilterOperator>Between</FilterOperator><FilterValue Type=\"Date\">2009-07-16T08:28:01Z</FilterValue><FilterValue Type=\"Date\">2019-07-17T08:28:01Z</FilterValue></FilterCriteria> </FilterGroup></FilterDefinition>" \
}' 'https://sampleapi.allegiancetech.com/HttpService.svc/web/getOptOuts'

Notes

Gets a filtered list of questions for a given survey ID.

URL

Parameters

token=[Guid]      Required
Authentication token, which is retrieved by calling authenticate.

surveyId=[int]      Required
Specifies the survey for which questions will be returned. To find the survey Id, see this Knowledge Center article. For a readout of all surveys the authenticated user has access to, issue the call getSurveyList.

filterXml=[string]      Optional
A parameter in XML format to filter the result records. The filter must have the following XML format:

<FilterDefinition>
  <FilterGroup GroupOperator='...'>
    <FilterCriteria>
      <FilterColumn></FilterColumn>
      <FilterOperator></FilterOperator>
      <FilterValue></FilterValue>
      <FilterValue></FilterValue>
    </FilterCriteria>
    <FilterCriteria>
      ...
    </FilterCriteria>
      ...
  </FilterGroup>
</FilterDefinition>

The FilterGroup GroupOperator can be defined with the operators AND and OR. Here are the columns available for filters, their possible values if applicable, and the operators that can be used on them:

• QuestionId; (Equals, NotEquals)
• QuestionText; (Equals, NotEquals, Contains, NotContains)
• LanguageId; (Equals, NotEquals)
• QuestionShortCode; (Equals, NotEquals, Contains, NotContains)
• QuestionAlias; (Equals, NotEquals, Contains, NotContains)
• QuestionStatus; [0 = active; 1 = deleted]; (Equals, NotEquals)
• QuestionType; [single, multi, text, memo, etc.]; (Equals, NotEquals)

Note: 1. Only a single FilterGroup per FilterDefinition is supported; 2. LanguageId will filter the answers to appear in the specified language – to determine the languages available for the survey, first call getLanguagesBySurveyId; 3. If no LanguageId is defined in the filter you will receive answers in the default survey language.

xmlIndent=[bool]      Optional
Specifies whether or not the resulting XML structure is formatted with newlines and indentation. Allowed parameters are true and false.

Sample Request